Query Statistics#

The queryStatistics method retrieves aggregated statistics for a specific health quantity type over a defined date range. It can compute metrics such as total sum, average, minimum, maximum, most recent value, and duration, with optional support for breaking down results by source (e.g., device or app).

This method is ideal for producing daily, weekly, or historical health summaries.

Method Signature#

1function queryStatistics(
2  quantityType: HealthQuantityType,
3  options?: {
4    startDate?: Date
5    endDate?: Date
6    strictStartDate?: boolean
7    strictEndDate?: boolean
8    statisticsOptions?: HealthStatisticsOptions | Array<HealthStatisticsOptions>
9  }
10): Promise<HealthStatistics | null>

Parameters#

quantityType: HealthQuantityType (required)#

The health quantity type to query, such as:

• "stepCount"
• "heartRate"
• "bodyMass"
• "activeEnergyBurned"
• Any supported HealthQuantityType

options (optional)#

An object specifying filtering and configuration options for the query.

Available HealthStatisticsOptions#

Return Value#

Returns a Promise that resolves to a HealthStatistics object, or null if no data is available for the given type and range.

Use the returned HealthStatistics object to access computed values like:

• sumQuantity(...)
• averageQuantity(...)
• mostRecentQuantity(...)
• duration(...)

Example: Query Daily Step Count Summary#

1const stats = await Health.queryStatistics("stepCount", {
2  startDate: new Date("2025-07-01"),
3  endDate: new Date("2025-07-02"),
4  statisticsOptions: ["cumulativeSum", "mostRecent", "duration"]
5})
6
7if (stats) {
8  const steps = stats.sumQuantity(HealthUnit.count())
9  const last = stats.mostRecentQuantity(HealthUnit.count())
10  const time = stats.duration(HealthUnit.second())
11
12  console.log("Steps:", steps)
13  console.log("Most recent count:", last)
14  console.log("Duration (s):", time)
15} else {
16  console.log("No step count data found.")
17}

Example: Query Average Heart Rate from This App Only#

1const stats = await Health.queryStatistics("heartRate", {
2  startDate: new Date("2025-07-01"),
3  endDate: new Date("2025-07-02"),
4  statisticsOptions: ["discreteAverage"]
5})
6
7const source = HealthSource.forCurrentApp()
8const averageHR = stats?.averageQuantity(HealthUnit.countPerMinute(), source)
9
10console.log("App-only Heart Rate:", averageHR)

Notes#

• If statisticsOptions is not specified, some fields (like sum, average, or most recent) may return null.
• This method returns aggregated values—to access raw samples, use queryQuantitySamples() instead.
• Results depend on the type of quantity. For instance, heart rate supports discreteAverage, while step count supports cumulativeSum.